Monster Media 1996 #14/Monster Media No. 14 (April 1996) (Monster Media, Inc.).ISO/netmail/yep13.zip/YEP.DOC

Text File | 1996-02-13 | 25KB | 564 lines

Y              E              P

Yarn Editor  Pre/Post Processor

Y              E              P

Version 1.3

Contents:
~~~~~~~~
        -1- Introduction to Yep
        -2- Installation of Yep
        -3- Tags & Substitution
        -4- Yep Operation Notes
                - . Translation
                - Mailing Lists
                - SIG-gy Tricks
        -5- Of Conditional Tags
        *6* History of Revision
        -7- Credits & Apologies



-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-
Introduction to Yep:
-------------------

   Yep is an "editor shell" for use specifically with the Yarn off-line
   newsreader (OS/2 version). It provides the following functionality:

        - Start your editor with the first line number past the message
          header, or quotes in a reply, (if your editor supports it)
        - Append your own lines to message headers.
        - Embedded macro tags at any point can:
                - import random lines of text (suitable for taglines,
                        SIG lines, random header messages, etc)
                - import files automatically into messages.
                - import random files (ie. useful for random SIGs)
                - execute programs (useful to create macros which
                        automatically import the text output of
                        a program)
                - conditionally do/print things based on current
                        newsgroup, to, date, or subject field.
                        (for example, have custom headers or SIG
                        files for particular newsgroups)
        - User defined substitution code table to create "macros" from
          the above tags, create custom abbreviations, or correct common
          spelling errors.
        - Optionally strip unused header entries when starting editor

   Yep is extremely configurable. The author likes to think of it as a
   program that can make every email an adventure! (-: It can be utilized
   in a simple manner for basic functions (like setting start up cursor
   positions), or in mind bogglingly complex customised craziness.

   It should be mentioned that there is already an excellent, and far
   more comprehensive "editor shell" for Yarn which is called "Yes". My
   reason for creating my own shell was mainly because there is no OS/2
   version of Yes (at this time); and also creating my own shell I can
   tailor it to my specific (and possibly insane) desires. I have no idea if
   anyone else may find it useful to them, but here it is.

   And after all, you could set yourself up to use both Yep and Yes at the
   same time, if you really want to. (-:


-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-
Installation of Yep:
-------------------

   It doesn't matter what directory you place YEP.EXE in, just as long
   as the YEP.CFG is in the same directory.

   1. Edit your Yarn CONFIG file.

        Edit the line which begins "editor=". This line should now read:

                editor=<path>\YEP.EXE

        where <path> is the path to wherever you placed the YEP.EXE.
        Note: Yep should have no parameters on that line. You will
        define the command line for you editor in the YEP.CFG file.

   2. Edit your YEP.CFG file.

        There are comments in this file (all lines beginning with a
        semi-colon (;) are comment lines), so not many details will be
        given in this document. Refer to the Yep.Cfg for instruction.

        You may use multiple copies of YEP for different users of yarn
        on your system. The YEP will always look for a CFG file that has
        the same root name as itself. Therefore if you made another
        copy of Yep and called it YEP2.EXE you would then create a
        YEP2.CFG file, which could have it's own set up.

        In the Yep.Cfg if you specify the full path (and EXE extension)
        of your editor it will be called directly and speed up loading
        a bit. Otherwise it is called though the command shell and your
        path is searched.

   That's all there is to basic installation. How you use and customize
   Yep is up to you.


-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-
Tags & Substitution:
-------------------

   A major concept of Yep is that of it's "macro" tags. Each message is
   scanned for substitutions and tags before the editor starts, as well
   as after the editor exits.  There are at this time only a few tags
   implemented (but many things can be done with them).

   All of the tags so far implemented are (in alphabetical order):

        EXEC:, IFDATE:, IFFLAG:, IFNG:, IFSUBJ:, IFTO:,
        IMPF:, IMPL:, RNDF:, RNDL:, SETFLAG:

   The basic syntax for tags are:

        {TAG:arguments}

   TAG is the name of the tag to be used, followed by a colon, followed
   immediately by information that the tag is to work with. Tags are
   not case sensitive-- they can be upper or lower or mixed case.

   Tags and substitutions are scanned sequentially on each line and
   therefore nesting (tags within tags) will not work. However all
   substitutions are done before any tags are interpreted, therefore
   you can put substitution codes inside tags (i'm not sure what for).

   Yep attempts to "translate" or "filter" all text that goes though
   it. It can get somewhat complex, but you can also include tags in
   imported files, and they will be honoured.


   {RNDL:filename}

        This tag will import a random line from the text file
        specified. The file can be of any length. Blank lines and
        lines beginning with a semi-colon (;) in the file will be
        ignored.

        This tag is useful for creating random "taglines" in your sig,
        or a random line in a header. It may have many other uses as
        well-- but that is up to you, and your imagination.

        For example, if in your YEP.CFG you had a header line like
        this:

                X-Funny-Line: {RNDL:funny.txt}

        In the above example the "X-Funny-Line:" header would be
        included in your message and a random line from a text file
        called "funny.txt" would follow it.


   {RNDF:filename}

        This tag inserts a random file. The "filename" specified will
        be considered a "root" or "base" filename (ie. the filename
        WITHOUT any extension). The directory containing the filename
        root will be scanned looking for files with that name having
        numbered extensions .1, .2, .3, and so on. The extension
        numbers must be sequential, with no gaps. A random file will
        be picked and inserted.


   {IMPF:filename}

        Very simply imports the "filename" file into your message.
        It could be useful for inserting external files into a SIG,
        or other places. For example, some people like to include
        their PGP key in their sig. You could do that by including
        {ImpF:c:\pgp\mykey.asc} in your SIG file (note: Yep does not
        append a SIG file itself, but interprets the SIG file that
        Yarn appends to each message). In this way if you upgrade
        PGP to a new version and export a new key to the filename
        noted above, your sig will always automatically have the
        latest extracted version of your key.


   {EXEC:filename arguments}

        This causes your message to stop and execute a file. The
        idea here is that you might have a file which output some
        text you would like to insert into the message: perhaps
        random quotations, or up to the second system statistics.
        You can execute the file with this tag and redirect the
        output to a temporary file, and then use the IMPF tag to
        read in the newly created temporary file.

        See the Yep.Cfg file for a few examples of this.

        As with the text editor configuration, if you specify
        a full path (with EXE extension) for your filename to
        EXEC then the program will be called directly, which
        speeds things up. Otherwise the file is run though the
        command processor and path is searched.

        Note: if you are using the EXEC tag to capture output
        using standard I/O redirection, do NOT include the EXE
        on the path/filename, as the program must be executed
        indirectly through your command processor in order to do
        standard output redirection. (See below in the "substitutions"
        section for more details).


   {IMPL:#:filename}

        Perhaps there is a text file from which is only wanted a
        single specific line of text (for example: to grab a line
        of information from the output of a text file generated
        by some other program}. With the ImpL tag you specify the
        line number you wish to read where the # is (do not include
        a # symbol), followed by a colon (:), and the filename.

        As an example: perhaps in your mail headers you would like
        to display to the world how long your computer has been
        running. There is a nice utility called "Go" by Carston Wimmer
        (ftp://hobbes.nmsu.edu/os2/textutil/go_15.zip) which will
        display OS/2's "up time" (and will do much more). However
        the output of Go also includes title/copyright line of text
        which you don't want to import: all you want is the "up time"
        reported on line 3 of Go's report.

        The output of "go -ut" might look like this:

   GO! v1.5 - (c) 1993-95 by Carsten Wimmer <[e-mail]>

   Uptime:  1d 23h 56m 59s 364ms

        Therefore you might include in your yep.cfg a header
        definition which would look like this:

                X-{exec:go -ut >utmp}{impL:3:utmp}

        The first tag in the above example executes the "Go" utility
        with the "-ut" switch and redirects the output to a work file
        called "utmp". The next tag then directs Yep to import line
        three, and only line three, of the work file that was created.

        Note also that the output of Go, with the -ut switch, includes
        a header-like "Uptime:", so in our example the fine output of
        your header would look like this:

                X-Uptime:  1d 23h 56m 59s 364ms



Substitutions:
-------------
   It would be rather awkward if you had to type in then entire tag,
   with filenames, and whatever other data that needs to be given,
   therefore you can define your own tags by using a substitution table.

   In the Yep.Cfg you may define (currently) up to 100 substitutions.

   For example, say you wanted a quick way to import your PGP public
   key into a message when someone asks for it. Rather than typing:
   {impf:c:\pgp\my.key}, you could set up a substitution in the Yep.Cfg
   something like this (refer to Yep.Cfg for details on the format):

        "{pk}"::"{impf:c:\pgp\my.key}"

   Now whenever you want to insert your PGP public key you would only
   need to quickly type {pk} in your message and it would be inserted.
   This is just an example, you could make it whatever you wanted.

   For another example, silly as it may be, say you had a fetish about
   how much disk drive space you have free at any given moment, and you
   are obsessed with telling everyone in every message how much drive
   space is available that very second. You could define a substitution
   something like so (assuming you have a utility called "free" which
   reports current free disk space):

        "{ds}"::"{exec:free >tmp}{impf:tmp}"

   In this way the "free" command is executed and its output is
   redirected to a temporary text file which is then imported into
   your message. (Note: if you are going to use ">" redirection
   to send output to a file, Yep needs to go through your OS command
   interpreter shell-- in this case do not include a full path to
   your program, as directly calls will not have redirected output.)


-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-
Yep Operation Notes:
-------------------

   Dot Translation:
   ===============
        When Yep runs you will see it announce itself, and then a
        series of coloured dots. (This behaviour can be turned off in
        the YEP.CFG if undesirable). Each dot tells which operation
        Yep has just completed during it's scanning and filtering
        activities. In this way you can tell how long certain
        operations take, as well as possibly debug certain problems;
        not to mention it's a form of cheep entertainment if you are
        tired of watching television.

        Yep begins by announcing itself as "Yep...". This just tells you
        the shell has started. After that dots follow:

        LIGHTBLUE - an user defined header line has been inserted.

        LIGHTGREEN - a substitution action has taken place.

        GREEN - A random line (RNDL) has been fetched (BLUE if it fails).

        BROWN - Yep has successfully imported a text file (IMPF/IMPR).

        YELLOW - Yep has attempted to import a text file but failed.

        GRAY - this is a potentially important dot: it indicates that
               yep is about to execute (EXEC) a program. A DARK grey dot
               means it is attempting to execute the program directly, a
               LIGHT gray dot means it is executing through your OS shell.
               This dot also shows up immediately before the Editor is
               called, so the user can see how quickly Yep pre-processes
               the file, and calls the editor (depending on system speed).

        BLUE - is a general error, and an error usually is given.

        After you finish editing your message Yep scans the message for
        any new processing instructions. The above colours apply. When
        it is finished it signs off with "...Yep" and returns you to Yarn.


   Mailing Lists:
   =============
        Rather a cheap hack, but one could, if one wanted, create a
        file with a comma separated list of addresses. Then create a
        substitution code which loads that file, something like:

                "{list1}"::"{IMPF:c:\yarn\MailLst1}"

        With this set up you only need to type {list1} in the Bcc: or
        Cc: field of your message and the list of addresses will be
        imported/substituted, and therefore mailed to everyone.

        Alternately you can just define a substitution that has your
        "mailing list" in it, and avoid having to import a file.

                "{L2}"::"[e-mail],[e-mail]"

        Note: addresses are separated by commas. In the above
        example if you entered {l2} in the To:, Cc: or Bcc: field
        of a message then it will be substituted with the comma
        delimited list.


   SIG-gy Tricks:
   =============
        Note: Yep does not append a SIG file, but relies on Yarn
        to append the SIG file. Yep however interprets whatever
        it finds in Yarn's SIG file allowing for many tricks.

        Using various substitution codes you can do quite flexible
        things with your SIG file. Not only can you have complete
        randomly chosen SIG files, and link external files, but
        individual elements inside your SIG can be randomized via
        the RNDL tag. For example, my current SIG file looks like
        this (this is just one small example of the possibilities):

{rndl:c:\osu\yarn\sig1top.lst}
  Tim Middleton {rndl:c:\osu\yarn\sig1luv.lst} [e-mail]
{rndl:c:\osu\yarn\sig1red.lst}
{rndl:c:\osu\yarn\sig1end.lst}

        What it does is gets a random top element from a list,
        then prints my name, inserts another random element from
        a different list, and then my email address. Furthermore,
        it then inserts another randomly chosen line, and finally
        a randomly chosen bottom element. The finally output
        might look like this (call me crazy, I love randomness!):

 .+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.
  Tim Middleton -with love and tomato sandwiches- [e-mail]
  -=-= brace yourself and read The Idiot by Fyodor Dostoyevsky =-=-
 ~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~


-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-
Of Conditional Tags:
-------------------

        The idea here is to give the user even more automated
        customization of their messages. For example, with conditional
        tags you can implement different SIGs based on the newsgroup
        being posted to. Or custom header lines based on who the
        message is To. This seemed like a good idea to me when I
        started working on it. Now I'm not sure if it's worth the
        trouble. You can safely ignore it if it doesn't sound useful
        to you.

        The way these tags work is that if the condition in them is
        met (ie. if it is true) then the rest of the line will be
        filtered through, otherwise the rest of the line will be
        discarded. If the conditional tag begins in column one and
        returns false then the entire line will be skipped.

        The new tags are:

   {IFTO:any text}

        If the text specified in the "any text" is found in the To:
        field of the header then the rest of the line is processed.


   {IFSUBJ:any text}

        Same as above, only the Subject: field is checked.


   {IFDATE:any text}

        Same as above, only the Date: field is checked. Perhaps you
        want special text automatically inserted into your messages
        on Fridays. I have no idea why!


   {IFNG:any text}

        Same as above, only the Newsgroups: field is checked. This
        one is possibly the most potentially useful; allowing custom
        headers or footer messages to be inserted when posting in
        certain newsgroups. Maybe. (For an example of how to use
        specific SIGs on individual newsgroups see IFFLAG below).


   {IFFLAG:true/false}

        This tag needs a little more explanation. Consider the following
        example Yarn SIG file (explanation to follow):

                {IfNG:comp.os2}{ImpF:c:\yarn\os2.sig}
                {IfNG:comp.windows}{ImpF:c:\yarn\wind.sig}
                {IfNG:alt.books}{ImpF:c:\yarn\book.sig}
                {IfFlag:false}{IfTO:peri strange}{ImpF:c:\yarn\peri.sig}
                {ifFlag:false}{ImpF:c:\yarn\default.sig}

        As you have hopefully noticed, this example sig tests to see
        if the user is posting in the various newsgroups: comp.os.*,
        comp.windows.*, and alt.books.*; and if so then imports the
        appropriate SIG file you have created.

        There is a global "FLAG" which begins always set to "false".
        Whenever a conditional tag returns a "true" status the global
        flag is set to "TRUE". Therefore in line four of the above SIG
        example, you are first testing to see if any of the above
        conditions have already been met. If they have then the rest
        of line four is skipped. If a sig has not yet been imported (so
        the global flag is still False) then it is checked to see if
        the message is to your good friend "Peri Strange"-- who gets
        his own sig to amuse him. Finally on the last line it is checked
        again if no other conditions returned true this line will use the
        "random file" tag to import a default SIG file with the name as
        specified. (see the {IMPF:filename} tag in section 3).

        Lines beginning with an "if" tag as the first thing on the line
        will not output anything (ie. will not leave a blank line) if
        any conditions being tested fail before any text is printed.


   {SETFLAG:true/false}

        There might be some circumstance, however unlikely, where you
        need to set or reset the global flag. An example would be if you
        have custom headers that test for certain dates or newsgroups,
        and then at the bottom of the message have a SIG that does more
        tests. To reset the global flag to FALSE simply put the following
        tag on a line starting in column one:

                {SetFlag:false}

        The line will be skipped in the message output, but the flag will
        be set to False at that point.


-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-
History of Revision:
-------------------

Version 1.3 - February 13, 1996
-----------
        - new tag "Import Line Number" {ImpL:#:filename} - will import
          a specified line number of a text file. See section 3.
        - a bug in the "IfFlag" logic found and fixed [thanks to
          [e-mail] (Cheryl Buzzell) for help finding this one].
        - the bug that almost killed me! Many thanks to the longsuffering
          [e-mail] (Tim Sawchuck) who reported the
          strange and mysterious "teh"::"the" substitution bug. After
          many, many trials and tribulations that could fill a long
          novel, suffice it to say-- it turned out to have nothing to
          do with that substitution (the symptom just shows up for Tim
          during it, but the bug (corruption) happens earlier), and this
          bug is officially (i hope) squashed, thank God, it nearly killed
          me. The problem, precisely, occurred if you used substitutions
          *IN* a custom header *AND* the replacement text was longer
          than the original text. I hope that clears it up for everyone!
        - faster, faster, faster. Yep should be noticeably faster
          (modified scanning routines), especially on long messages.
        - added a few more meaningful, english, error messages. (-;
        - [e-mail] (Andrew Shipton) finally noticed that
          Yep wasn't allowing Yarn 'score' files to get passed through to
          the editor. Doh! Fixed now, more or less! Sorry about that.
        - better handling of {IfFlag:} and {SetFlag:} so that blank lines
          are not left in a situation like this:

            {ifflag:false}{ifng:yarn}This is the yarn mail list.

          Previously if this "yarn" was not found in the newsgroups:
          header then an awkward blank line would have been left behind.
          No more. Should work much better with long lists of conditions
          in SIGs or headers.


Version 1.2 - February 4, 1996
-----------
        - very unfortunate bug that kept version 1.1 from running AT ALL
          with the default yep.cfg due an error and bad parsing of the
          [substitutions] section of yep.cfg. Fixed. Sorry! (If you
          removed all blank lines from the yep.cfg it would work)


Version 1.1 - January 31, 1996
-----------
        - the old 255 character per line limit is now 50,000.
        - new yep.cfg directive: CleanHeader = "No"/"Yes" (see yep.cfg)
          [thanks to suggestion by someone whom I lost the email of]
        - new yep.cfg directive: ShowDots = "Yes"/"No" (see yep.cfg)
        - $l (lower case L) in yep.cfg Editor= statement sets cursor
          line number to the first line after the quotes in a reply.
          [thanks to suggestion by [e-mail]]
        - bizarre new experimental conditional tags: please see section
          5 of this document above for details if interested.
        - custom header lines increased from 12 to 50
        - maximum substitutions raised from 25 to 100
        - new yep.cfg directive: CursorAdjust (see yep.cfg)

Version 1.0 - December 31, 1995
-----------
        - Released. Sort of.


-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-
Credits:
-------

Yarn off-line news/mail reader of DOS and OS/2 (the reason we are gathered
here today, dearly beloved) is by Chin Huang. (ftp://ftp.oce.com/pub/yarn/)

Yes (Yarn Editor Shell) is by [it doesn't say until you run the install
program which I don't feel like doing at the moment, but you can get it
yourself and check it out as well at...] (ftp://ftp.oce.com/pub/yarn/)

And lastly and leastly there's me: Tim Middleton ([e-mail])

Sorry if this documentation is a bit crappy and not explained well. (-:

[Here ends the documentation for YEP 1.3, February 13, 1996]